PREF_GET

The PREF_GET function returns information about IDL preferences. It can return any of the following information:

The current effective value for a given preference (specified by PrefName)
The names of all the preferences (specified by /NAMES_ALL)
The number of pending preferences (specified by /NUM_PENDING); that is, the ones that have had a value set (PREF_SET), but not committed (PREF_COMMIT)
Detailed information for a given preference (specified by PrefName and /STRUCTURE), including:
A string giving a description of the preference’s purpose
The current effective value and its source
Whether the value is read-only
Any minimum or maximum values within which the preference must fit
Whether or not the preference accepts a fixed (discrete) set of values, and any mnemonic names allowed for each value.

Syntax

Result = PREF_GET( [PrefName] [, /NAMES_ALL | /NUM_PENDING | /STRUCTURE ] )

Return Value

The default return value is a scalar returning the current effective value for the named preference (specified by PrefName).

If the NAMES_ALL keyword is set, the return value is a string array containing the names of all the preferences.

If the NUM_PENDING keyword is set, the return value is an integer count of the number of preferences that currently have a value that was set (by PREF_SET) and not committed.

If the STRUCTURE keyword is set, the return value is a structure providing full details on the preference specified by PrefName. For more information see the Information Returned by STRUCTURE Keyword section in this topic.

Arguments

PrefName

The name of the preference for which information is desired.

Keywords

NAMES_ALL

If this keyword is set, PREF_GET returns a string array containing the names of all the preferences.

NUM_PENDING

If this keyword is set, PREF_GET returns the number of preferences within IDL that currently have a value that was set (by PREF_SET) and not yet committed.

STRUCTURE

Set this keyword to cause PREF_GET to return a structure giving detailed information about the preference specified by PrefName. For more information, see the topic Information Returned by STRUCTURE Keyword (below).

Information Returned by STRUCTURE Keyword

If the STRUCTURE keyword is set, PREF_GET returns a structure giving detailed information about the preference. The type and number of fields present in the returned structure depends on the preference in question. Every such result will contain the same set of initial fields. Based on the information provided by these initial fields, there may be additional fields that supply extra information.

The fields contained in the returned structure are:

NAME: A string giving the name of the preference.
DESCRIPTION: A string giving a one line description of the preference.

CURRENT_SOURCE: A string that reports the source of the current effective value. The following values for this field are possible (listed in ascending order of the source’s priority):

DEFAULT	IDL's built in default value for this preference
USERFILE	User preference file
DISTFILE	Preference file from the `resource/pref` directory of the IDL distribution.
ENV	Environment variable
CMDLINE	Command line option

COMMIT_SEEN: A string that describes when IDL will begin to use the new value of the preference once it has been committed. The following values are possible:

IMMEDIATE	Value will take effect immediately after commit
RESET	Value will take effect after the next `.reset_session` or `.full_reset_session`, or in subsequent IDL sessions
RESTART	Value will not take effect in this IDL session, but will be used in subsequent IDL sessions

READONLY: True (1) if the preference is read-only and false (0) otherwise. A preference is read-only if its value is currently being set by a source with a higher precedence than that of the user’s preference file. See CURRENT_SOURCE above for the hierarchy of source priority.
HAS_MIN, VALUE_MIN: HAS_MIN is true (1) if the preference value is required to be greater than or equal to a minimum value. It is false (0) if there is no minimum value. If HAS_MIN is true, the returned structure also contains a field named VALUE_MIN that contains the minimum value. If HAS_MIN is false, VALUE_MIN is not present.
HAS_MAX, VALUE_MAX: HAS_MAX is true (1) if the preference value is required to be less than or equal to a maximum value. It is false (0) if there is no maximum value. If HAS_MAX is true, the returned structure will also contain a field named VALUE_MAX that contains the maximum value. If HAS_MAX is false, VALUE_MAX is not present.

HAS_DISCRETE_VALUES, NUM_VALUES, VALUES, NUM_ALIAS, ALIAS_VALUES: HAS_DISCRETE_VALUES is true (1) if the preference value must come from a predefined list of possible values. It is false (0) otherwise. Although preferences with discrete values are always numeric, IDL lets the values be referenced by mnemonic names called aliases. If HAS_DISCRETE_VALUES is true, the returned structure also contains fields that supply additional information about the values. If HAS_DISCRETE_VALUES is false (0), these extra fields are not present (listed in the order in which they appear in the structure):

NUM_VALUES	The number of discrete values.
VALUES	An array of NUM_VALUES elements. Each element contains one of the allowed values for this preference.
NUM_ALIAS	An array of NUM_VALUES elements. Each element reports the number of alias names that exist for the corresponding value in VALUES.
ALIAS_VALUES	An array of size [MAX(NUM_ALIAS), NUM_VALUES]. Each row of ALIAS_VALUES gives the alias names that are allowed for the corresponding element of VALUES. For example, the aliases allowed for the first value (VALUES[0]) is ALIAS_VALUES[0:NUM_ALIAS[0], 0].

HAS_PENDING: True (1) if the preference has a currently pending value. A pending value is a value that has been set (by PREF_SET) but not yet committed. If HAS_PENDING is true, the VALUE_PENDING field contains the pending value.
VALUE_EFFECTIVE: The current effective value for the preference.
VALUE_DEFAULT: IDL's built in default value for the preference. This is the value IDL uses if no other source is present.
VALUE_PENDING: If HAS_PENDING is true (1), this field contains the pending value. Otherwise, it will contain 0 (numeric) or an empty string, depending on the type of the preference.

Version History

6.2	Introduced